Overcoming GitHub Repository Limitations

A comprehensive analysis of strategies to work around GitHub’s free tier limitations for repository size, bandwidth, and storage
Author

Dario Airoldi

Published

August 25, 2025

Modified

November 3, 2025

Overcoming GitHub Repository Limitations

Table of Contents

  1. 📚 Introduction
  2. ⚠️ Understanding GitHub Free Tier Limitations
  3. 🔍 Problem Analysis
  4. 🎯 Solution Options Overview
  5. 💳 Option 1: GitHub Paid Plans
  6. 🔄 Option 2: Alternative Git LFS Providers
  7. 🛠️ Option 3: Custom Git LFS Server
  8. ☁️ Option 4: External Storage with File Links
  9. 📦 Option 5: GitHub Releases for Large Assets
  10. 🔧 Option 6: Repository Optimization
  11. 📊 Comparison Matrix
  12. 🚀 Implementation Recommendations
  13. 📖 Case Study: Learn Repository Solution
  14. 🎉 Conclusion
  15. 📚 References

📚 Introduction

GitHub’s free tier provides excellent value for most projects, but certain limitations can become problematic for repositories with large files, extensive documentation, or high bandwidth usage.

This article analyzes practical strategies to overcome these limitations while maintaining functionality and cost-effectiveness.

Our analysis is based on a real-world case study of a learning repository that exceeded GitHub’s Git LFS bandwidth limits, resulting in blocked operations and additional charges.
We explore multiple solution approaches, from simple paid upgrades to sophisticated custom implementations.

⚠️ Understanding GitHub Free Tier Limitations

Repository Size & Storage Constraints

Limitation Free Tier Impact
Repository Size 1 GB (soft limit) Warnings, potential contact from GitHub
File Size 100 MB per file Warnings, push failures for larger files
Git LFS Storage 1 GB total Limited capacity for large binary files
Git LFS Bandwidth 1 GB/month Downloads count against quota

GitHub Actions Limitations

Resource Free Tier Impact
Compute Minutes 2,000/month Limited CI/CD capacity
Storage 500 MB Artifacts and logs storage
Concurrent Jobs 20 Parallel execution limits
Job Duration 6 hours max Long-running processes fail

GitHub Pages Limitations

Resource Free Tier Impact
Site Size 1 GB maximum Total published site size limit
Monthly Bandwidth 100 GB soft limit Traffic and download restrictions
Build Minutes Shared with Actions Uses same 2,000 minute quota
Custom Domains 1 per repository Limited domain configuration
HTTPS Enforcement Automatic for *.github.io Required for custom domains

Documentation Site Challenges

GitHub Pages limitations can significantly impact documentation repositories:

Site Type Typical Size Potential Issues
Simple Documentation 50-200 MB Usually within limits
Media-Rich Learning Site 500 MB - 2 GB Exceeds 1 GB limit
Conference Documentation 1-5 GB Requires external hosting
Multi-language Docs 300 MB - 1.5 GB May hit size restrictions

Bandwidth Consumption Patterns

Documentation sites can consume substantial bandwidth:

  • PDF Downloads: 100 downloads × 50MB = 5GB bandwidth
  • Video Streaming: 50 views × 100MB = 5GB bandwidth
  • Image Assets: High-resolution screenshots and diagrams
  • Search Indexing: Automated crawlers accessing content
  • CDN Misses: Direct GitHub Pages bandwidth usage

Build Process Limitations

GitHub Pages builds share resources with GitHub Actions:

  • Quarto Rendering: Complex sites may require 10-30 minutes per build
  • Large Asset Processing: Image optimization and file processing
  • Multiple Environment Builds: Development, staging, production
  • Frequent Updates: Documentation changes triggering rebuilds

Monthly Impact Example:

Daily documentation updates: 30 builds × 15 minutes = 450 minutes
Weekly major updates: 4 builds × 45 minutes = 180 minutes  
Monthly refactoring: 2 builds × 90 minutes = 180 minutes
Total: 810 minutes (40% of free quota)

Additional Constraints

  • Private Repository Collaborators: 3 maximum
  • API Rate Limits: 5,000 requests/hour
  • Package Storage: 500 MB for GitHub Packages
  • Support: Community-only (no priority support)

Understanding the Interconnected Impact

The Compound Effect of Multiple Limitations

GitHub’s free tier limitations don’t operate in isolation—they create a compound effect that can rapidly escalate costs and complexity for documentation-heavy repositories:

Repository + LFS + Pages Triangle:

Large Repository (approaching 1GB)
    ↓
Git LFS for large files (1GB limit)
    ↓  
GitHub Pages site (1GB limit)
    ↓
All sharing same storage constraints

Documentation Site Bottlenecks

Multi-Tier Storage Pressure:

  • Source Repository: Markdown, code, small assets
  • Git LFS: PDFs, videos, large images
  • GitHub Pages: Rendered HTML, processed assets
  • Actions Artifacts: Build outputs, temporary files

Each tier has independent limits that can be exceeded simultaneously.

Cost Escalation Scenarios

Scenario 1: Popular Learning Repository

Repository: 800MB (source files)
Git LFS: 2GB (conference videos) → $0.50 overage
Pages Traffic: 150GB/month → Potential throttling
Actions: 3,000 minutes/month → $16 overage
Monthly Impact: $16.50 + performance degradation

Scenario 2: Enterprise Documentation

Repository: 1.2GB → GitHub contact/warnings
Git LFS: 10GB → $4.50 overage  
Pages: 2GB site → Exceeds limit, hosting fails
Actions: 8,000 minutes → $48 overage
Monthly Impact: $52.50 + complete hosting failure

Technical Interdependencies

Build Process Chain Reaction:

  1. Large source files → Extended build times → Actions quota consumption
  2. LFS bandwidth limits → Failed asset downloads → Broken builds
  3. Pages size limits → Incomplete site deployment → User experience issues
  4. Combined limits → Development workflow disruption → Team productivity impact

Performance and User Experience Impact

Documentation Site Performance:

  • Large pages load slowly from GitHub’s CDN
  • Missing assets when LFS bandwidth exceeded
  • Broken builds when multiple limits hit simultaneously
  • Inconsistent availability during quota resets

Developer Experience Degradation:

  • Failed pushes when repository approaches 1GB
  • Broken CI/CD when Actions minutes exhausted
  • Manual intervention required for large file management
  • Split workflows across multiple platforms

🔍 Problem Analysis

Common Scenarios Leading to Limitations

  1. Documentation Repositories: Large PDFs, videos, images
  2. Learning Materials: Conference recordings, presentation files
  3. Sample Projects: Binary dependencies, datasets
  4. Multi-media Content: Graphics, audio, video files
  5. Automated Builds: Frequent CI/CD operations

Cost Impact

When exceeding free tier limits, costs can escalate dramatically, especially for documentation sites with substantial static content:

Git LFS Overage Examples

  • Small Documentation Site (5 GB images/PDFs): ~$2/month in LFS overages
  • Medium Learning Repository (50 GB conference materials): ~$25/month in LFS overages
  • Large Documentation Site (500 GB multimedia content): ~$250/month in LFS overages
  • Enterprise Knowledge Base (2 TB assets): ~$1,000/month in LFS overages

Real-World Cost Scenarios

Documentation repositories commonly accumulate large static content:

Content Type Typical Size Monthly LFS Cost
Conference recordings (100 sessions) 200 GB $100/month
Product documentation with screenshots 50 GB $25/month
Training materials (videos + PDFs) 500 GB $250/month
Marketing assets (high-res images) 100 GB $50/month

Actions Overage Impact

  • Frequent documentation builds: 5,000+ minutes/month = $24/month additional
  • Large repository clones with LFS: Each clone consumes bandwidth quota
  • Multi-environment deployments: Development, staging, production builds multiply costs

Compounding Factors

  • Team collaboration: Multiple developers cloning = multiplied bandwidth usage
  • CI/CD pipelines: Automated builds pulling LFS files repeatedly
  • Documentation updates: Frequent changes to large files trigger LFS transfers
  • Unpredictable growth: Static content accumulates over time without monitoring

Cost in size can be multiplied by cost in bandwidth, especially with multiple users and CI/CD pipelines.

🎯 Solution Options Overview

We identified six primary approaches to overcome GitHub limitations:

  1. Upgrade to paid GitHub plans
  2. Use alternative Git LFS providers
  3. Implement custom Git LFS server
  4. External storage with file links
  5. GitHub Releases for large assets
  6. Repository optimization strategies

💳 Option 1: GitHub Paid Plans

Overview

Upgrade to GitHub Pro, Team, or Enterprise for higher limits and predictable costs.

Pricing & Limits

Plan Cost Git LFS Actions Minutes Private Repos
Free $0 1 GB storage, 1 GB bandwidth 2,000 minutes Limited collaborators
Pro $4/month 1 GB storage, 1 GB bandwidth 3,000 minutes Unlimited
Team $4/user/month 1 GB storage, 1 GB bandwidth 3,000 minutes Advanced features
Enterprise $21/user/month 1 GB storage, 1 GB bandwidth 50,000 minutes Enterprise features

Additional LFS Storage: No longer available as “data packs” - overages charged at ~$0.50/GB

Pros

  • ✅ Simple implementation - Just upgrade account
  • ✅ Official support - Full GitHub integration
  • ✅ Predictable costs - Known monthly fees
  • ✅ Additional features - Advanced security, analytics
  • ✅ No technical complexity - Works with existing workflows

Cons

  • ❌ Limited LFS improvement - Same 1 GB base allocation
  • ❌ Overage charges continue - Still pay per GB over limit
  • ❌ Recurring costs - Monthly subscription fees
  • ❌ Not cost-effective - For high LFS usage scenarios

Implementation

# No technical implementation required
# 1. Go to GitHub.com → Settings → Billing and plans
# 2. Upgrade to desired plan
# 3. Configure spending limits if desired

Best For

  • Professional developers needing advanced features
  • Teams requiring collaboration tools
  • Projects with moderate overage needs
  • Organizations wanting official support

🔄 Option 2: Alternative Git LFS Providers

Overview

Use third-party Git LFS providers that offer more generous free tiers or better pricing.

Provider Comparison

Provider Free Tier Pricing Integration
GitLab 10 GB storage, 10 GB bandwidth $4/month for 100 GB Excellent
Bitbucket 5 GB storage, 5 GB bandwidth $3/month for 100 GB Good
Azure DevOps Unlimited public repos $6/month for private Good
Codeberg 4 GB per repo Free/donations Basic

Pros

  • ✅ Higher free limits - Up to 10x more storage/bandwidth
  • ✅ Better pricing - More cost-effective for high usage
  • ✅ Standard Git LFS - Compatible with existing workflows
  • ✅ Multiple options - Various providers to choose from
  • ✅ Easy migration - Can mirror existing repositories

Cons

  • ❌ Multiple repositories - Must maintain sync between providers
  • ❌ Complexity overhead - Managing multiple remotes
  • ❌ Potential vendor lock-in - LFS files tied to specific provider
  • ❌ CI/CD complications - May need to update workflows

Implementation Steps

  1. Choose alternative provider (GitLab recommended)
  2. Create mirrored repository
  3. Configure LFS endpoint in .lfsconfig
  4. Update CI/CD workflows if necessary
  5. Test complete workflow before full migration

Best For

  • Projects with high LFS storage needs
  • Teams comfortable managing multiple Git remotes
  • Cost-sensitive applications
  • Open source projects (many providers offer free tiers)

🛠️ Option 3: Custom Git LFS Server

Overview

Implement a custom Git LFS server using cloud storage as the backend, providing unlimited storage at cloud storage prices.

Architecture Options

A. Azure Functions + Blob Storage

[FunctionName("LfsBatch")]
public async Task<IActionResult> Batch(
    [HttpTrigger(AuthorizationLevel.Function, "post", Route = "objects/batch")] 
    HttpRequest req)
{
    var request = await req.ReadFromJsonAsync<LfsBatchRequest>();
    var response = new LfsBatchResponse();
    
    foreach (var obj in request.Objects)
    {
        var sasUrl = GenerateBlobSasUrl(obj.Oid, obj.Size);
        response.Objects.Add(new LfsObject
        {
            Oid = obj.Oid,
            Size = obj.Size,
            Actions = new Dictionary<string, LfsAction>
            {
                ["upload"] = new LfsAction { Href = sasUrl, ExpiresIn = 3600 }
            }
        });
    }
    
    return new OkObjectResult(response);
}

B. Docker Container Solution

# docker-compose.yml
version: '3.8'
services:
  lfs-server:
    image: jasonwhite/rudolfs
    ports:
      - "8080:8080"
    environment:
      - RUDOLFS_AZURE_STORAGE_ACCOUNT=youraccount
      - RUDOLFS_AZURE_STORAGE_KEY=yourkey
      - RUDOLFS_HOST=0.0.0.0:8080
    volumes:
      - ./data:/data

C. AWS Lambda + S3

// lambda function for LFS batch API
exports.handler = async (event) => {
    const request = JSON.parse(event.body);
    const response = {
        objects: request.objects.map(obj => ({
            oid: obj.oid,
            size: obj.size,
            actions: {
                upload: {
                    href: generateS3PresignedUrl(obj.oid),
                    expires_in: 3600
                }
            }
        }))
    };
    
    return {
        statusCode: 200,
        body: JSON.stringify(response)
    };
};

Cost Analysis

Component Azure AWS Google Cloud
Storage (per GB/month) $0.018 (Cool) $0.023 (IA) $0.020 (Nearline)
Bandwidth (per GB) $0.087 $0.09 $0.12
Compute Functions: $0.20/1M requests Lambda: $0.20/1M requests Functions: $0.40/1M requests
Total (50GB storage + 10GB bandwidth) ~$2.50/month ~$3.00/month ~$3.50/month

Pros

  • ✅ Unlimited storage - Use cheap cloud storage (~$1.80/50GB/month)
  • ✅ Full control - Own your LFS infrastructure
  • ✅ Cost effective - Pay only for usage
  • ✅ Scalable - Handle repositories of any size
  • ✅ Learning opportunity - Great technical project
  • ✅ Vendor independence - Not locked to any Git provider

Cons

  • ❌ Implementation complexity - Requires development work
  • ❌ Maintenance overhead - Need to maintain and update
  • ❌ Hosting costs - Additional infrastructure expenses
  • ❌ Reliability concerns - Must ensure high availability
  • ❌ Security responsibility - Handle authentication and authorization

Implementation Approaches

Quick Start: Pre-built Solutions

# Option 1: Use Rudolfs (Rust-based LFS server)
docker run -d \
  -p 8080:8080 \
  -e RUDOLFS_AZURE_STORAGE_ACCOUNT=learnprod01 \
  -e RUDOLFS_AZURE_STORAGE_KEY=your-key \
  -e RUDOLFS_HOST=0.0.0.0:8080 \
  jasonwhite/rudolfs

# Option 2: Use lfs-server-go
docker run -d \
  -p 8080:8080 \
  -e LFS_STORAGE_TYPE=azure \
  -e AZURE_STORAGE_ACCOUNT=learnprod01 \
  -e AZURE_STORAGE_KEY=your-key \
  lfs-server-go

Custom Development Steps

  1. Choose cloud platform (Azure, AWS, GCP)
  2. Implement LFS API endpoints:
    • POST /objects/batch - Request upload/download URLs
    • PUT /objects/{oid} - Upload objects (via pre-signed URLs)
    • GET /objects/{oid} - Download objects (via pre-signed URLs)
  3. Set up storage backend
  4. Configure authentication
  5. Deploy and test

Best For

  • Technical teams comfortable with cloud development
  • Projects requiring maximum cost efficiency
  • Organizations wanting full control over their LFS infrastructure
  • Learning environments exploring Git LFS internals

📦 Option 5: GitHub Releases for Large Assets

Overview

Use GitHub Releases to distribute large files without affecting repository size or LFS quotas.

Release-Based File Management

Creating Releases for Assets

# Using GitHub CLI
gh release create v1.0.0 \
  --title "Build 2025 Conference Materials" \
  --notes "Complete conference materials including presentations and recordings" \
  build2025-presentations.zip \
  build2025-recordings.zip \
  build2025-samples.zip

# Using API
curl -X POST \
  -H "Authorization: token $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/username/repo/releases \
  -d '{
    "tag_name": "assets-v1.0.0",
    "name": "Large Assets v1.0.0",
    "body": "Conference materials and large files",
    "draft": false,
    "prerelease": false
  }'

Automated Release Creation

# .github/workflows/create-release.yml
name: Create Release for Large Files

on:
  push:
    tags:
      - 'assets-v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    
    - name: Create Release
      uses: actions/create-release@v1
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      with:
        tag_name: ${{ github.ref }}
        release_name: Large Assets ${{ github.ref }}
        draft: false
        prerelease: false
    
    - name: Upload Assets
      uses: actions/upload-release-asset@v1
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      with:
        upload_url: ${{ steps.create_release.outputs.upload_url }}
        asset_path: ./large-files.zip
        asset_name: large-files.zip
        asset_content_type: application/zip

Documentation Integration

## Conference Materials

### Latest Release: [Build 2025 Materials](https://github.com/username/repo/releases/tag/build2025-v1.0.0)

#### Available Downloads:

- **Presentations** ([download](https://github.com/username/repo/releases/download/build2025-v1.0.0/presentations.zip)) - 156 MB
  - All keynote and session presentations in PDF format
  - Speaker notes and additional materials
  
- **Video Recordings** ([download](https://github.com/username/repo/releases/download/build2025-v1.0.0/recordings.zip)) - 2.1 GB
  - Full session recordings in MP4 format
  - Audio-only versions for mobile listening
  
- **Code Samples** ([download](https://github.com/username/repo/releases/download/build2025-v1.0.0/code-samples.zip)) - 45 MB
  - Complete working examples from all sessions
  - Setup instructions and documentation

### Previous Releases:

- [Build 2024 Materials](https://github.com/username/repo/releases/tag/build2024-v1.0.0)
- [Build 2023 Materials](https://github.com/username/repo/releases/tag/build2023-v1.0.0)

Pros

  • ✅ No LFS quota impact - Releases don’t count against LFS limits
  • ✅ Integrated with GitHub - Native GitHub functionality
  • ✅ Version controlled - Each release is tagged and dated
  • ✅ Download statistics - GitHub provides download metrics
  • ✅ Easy access - Direct download links for users
  • ✅ No additional costs - Free with GitHub repositories

Cons

  • ❌ Manual release process - Must create releases for each version
  • ❌ Not suitable for frequent updates - Best for stable assets
  • ❌ Large file limits - Individual files still limited to 2GB
  • ❌ No partial updates - Must re-upload entire archives
  • ❌ Download required - Users must download to access content

Implementation Workflow

1. Organize Large Files

# Create organized archives
mkdir -p releases/build2025/{presentations,videos,code}

# Move large files to release directories
cp *.pdf releases/build2025/presentations/
cp *.mp4 releases/build2025/videos/
cp -r code-samples/ releases/build2025/code/

# Create archives
cd releases/build2025
zip -r ../presentations-build2025.zip presentations/
zip -r ../videos-build2025.zip videos/
zip -r ../code-build2025.zip code/

2. Create Release Script

#!/bin/bash
# create-release.sh
TAG_NAME="$1"
RELEASE_NAME="$2"
DESCRIPTION="$3"

if [ -z "$TAG_NAME" ]; then
    echo "Usage: $0 <tag_name> <release_name> <description>"
    exit 1
fi

# Create release
gh release create "$TAG_NAME" \
  --title "$RELEASE_NAME" \
  --notes "$DESCRIPTION" \
  releases/*.zip

echo "Release created: https://github.com/$(gh repo view --json owner,name -q '.owner.login + "/" + .name')/releases/tag/$TAG_NAME"

3. Update Documentation

# update-release-docs.sh
TAG_NAME="$1"
REPO_URL=$(gh repo view --json url -q '.url')

cat >> README.md << EOF

## Latest Release: [$TAG_NAME]($REPO_URL/releases/tag/$TAG_NAME)

Download the latest conference materials and resources.

EOF

Best For

  • Educational repositories with periodic large file updates
  • Conference and event documentation
  • Software distributions with large binary files
  • Projects with stable, versioned large assets

🔧 Option 6: Repository Optimization

Overview

Optimize repository structure and content to stay within GitHub’s free tier limitations through strategic file management and Git practices.

Repository Analysis Tools

Git Repository Size Analysis

# Analyze repository size
git count-objects -vH

# Find large files in history
git rev-list --objects --all | \
  git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | \
  sed -n 's/^blob //p' | \
  sort --numeric-sort --key=2 | \
  cut -c 1-12,41- | \
  $(command -v gnumfmt || echo numfmt) --field=2 --to=iec-i --suffix=B --padding=7 --round=nearest

# Identify large files by type
find . -type f -exec du -Sh {} + | sort -rh | head -20

LFS Usage Analysis

# Check current LFS usage
git lfs ls-files --size

# Find files that should be in LFS
find . -type f -size +100M -not -path "./.git/*"

# Analyze LFS bandwidth usage (if available in logs)
git lfs logs last

Optimization Strategies

A. Selective LFS Tracking

# Remove unnecessary files from LFS
git lfs untrack "*.jpg"  # If images are small
git lfs untrack "*.png"  # Remove from LFS if under 10MB

# Track only truly large files
git lfs track "*.zip"
git lfs track "*.pdf"
git lfs track "*.mp4" 
git lfs track "*.psd"

# Update .gitattributes
git add .gitattributes
git commit -m "Optimize LFS tracking for file sizes"

B. Repository Restructuring

# Create separate repositories for different content types
mkdir -p ../Learn-Docs ../Learn-Media ../Learn-Code

# Move large files to appropriate repositories
mv *.pdf ../Learn-Docs/
mv *.mp4 ../Learn-Media/
mv code-samples/ ../Learn-Code/

# Link repositories via submodules
git submodule add https://github.com/username/Learn-Docs.git docs
git submodule add https://github.com/username/Learn-Media.git media
git submodule add https://github.com/username/Learn-Code.git code

C. Git History Optimization

# Remove large files from Git history (DANGEROUS - backup first!)
git filter-branch --tree-filter 'rm -rf large-files-directory' HEAD
git push origin --force --all

# Alternative: BFG Repo-Cleaner (safer)
java -jar bfg-1.14.0.jar --delete-files "*.{zip,pdf,mp4}" .git
git reflog expire --expire=now --all && git gc --prune=now --aggressive

Smart File Management

Conditional LFS Tracking

# Create script to automatically track large files
#!/bin/bash
# auto-lfs-track.sh

THRESHOLD_MB=10
find . -type f -size +${THRESHOLD_MB}M -not -path "./.git/*" | while read file; do
    extension="${file##*.}"
    
    # Check if extension is already tracked
    if ! grep -q "*.${extension} filter=lfs" .gitattributes; then
        echo "*.${extension} filter=lfs diff=lfs merge=lfs -text" >> .gitattributes
        echo "Added ${extension} files to LFS tracking"
    fi
done

# Sort and deduplicate .gitattributes
sort .gitattributes | uniq > .gitattributes.tmp
mv .gitattributes.tmp .gitattributes

Progressive File Management

# Create tiered storage strategy
mkdir -p {current,archive-2024,archive-2023}

# Move old files to archive directories
mv 2023-conferences/ archive-2023/
mv 2024-conferences/ archive-2024/

# Create archive repositories for old content
git submodule add https://github.com/username/Learn-Archive-2023.git archive-2023
git submodule add https://github.com/username/Learn-Archive-2024.git archive-2024

Automated Optimization

Pre-commit Hook for Size Checking

#!/bin/bash
# .git/hooks/pre-commit

# Check for large files
large_files=$(find . -type f -size +100M -not -path "./.git/*")

if [ -n "$large_files" ]; then
    echo "❌ Large files detected (>100MB):"
    echo "$large_files"
    echo ""
    echo "Consider:"
    echo "  1. Adding to Git LFS: git lfs track 'filename'"
    echo "  2. Moving to external storage"
    echo "  3. Compressing the file"
    echo ""
    echo "To bypass this check: git commit --no-verify"
    exit 1
fi

# Check LFS bandwidth usage (if tracking available)
if command -v git-lfs &> /dev/null; then
    lfs_size=$(git lfs ls-files --size | awk '{sum += $2} END {print sum/1024/1024}')
    if (( $(echo "$lfs_size > 800" | bc -l) )); then
        echo "⚠️  Warning: LFS usage approaching 1GB limit (${lfs_size}MB)"
    fi
fi

GitHub Actions for Repository Health

# .github/workflows/repo-health.yml
name: Repository Health Check

on:
  push:
    branches: [main]
  schedule:
    - cron: '0 0 * * 0'  # Weekly

jobs:
  analyze:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v4
      with:
        fetch-depth: 0  # Full history for analysis
        
    - name: Analyze Repository Size
      run: |
        echo "## Repository Size Analysis" >> $GITHUB_STEP_SUMMARY
        git count-objects -vH >> $GITHUB_STEP_SUMMARY
        
    - name: Check Large Files
      run: |
        echo "## Files >10MB" >> $GITHUB_STEP_SUMMARY
        find . -type f -size +10M -not -path "./.git/*" -exec ls -lh {} \; >> $GITHUB_STEP_SUMMARY || echo "No large files found" >> $GITHUB_STEP_SUMMARY
        
    - name: LFS Usage Report
      if: hashFiles('.gitattributes') != ''
      run: |
        echo "## Git LFS Files" >> $GITHUB_STEP_SUMMARY
        git lfs ls-files --size >> $GITHUB_STEP_SUMMARY || echo "No LFS files" >> $GITHUB_STEP_SUMMARY
        
    - name: Recommendations
      run: |
        echo "## Optimization Recommendations" >> $GITHUB_STEP_SUMMARY
        
        # Check for untracked large files
        untracked_large=$(find . -type f -size +50M -not -path "./.git/*" -not -path "./.lfs/*")
        if [ -n "$untracked_large" ]; then
          echo "⚠️ Consider adding these files to Git LFS:" >> $GITHUB_STEP_SUMMARY
          echo "$untracked_large" >> $GITHUB_STEP_SUMMARY
        fi
        
        # Repository size warning
        repo_size=$(du -sh .git | cut -f1)
        echo "📊 Repository size: $repo_size" >> $GITHUB_STEP_SUMMARY

Best For

  • Teams committed to long-term repository health
  • Projects with mixed content types
  • Educational repositories with evolving content
  • Organizations with Git expertise
  • Cost-conscious projects willing to invest time

🚀 Implementation Recommendations

Immediate Actions (Day 1)

  1. Assess current usage via GitHub billing page
  2. Identify problem files using repository analysis tools
  3. Implement quick wins (remove unnecessary LFS tracking)
  4. Set up monitoring to track future usage

Short-term Strategy (Week 1-2)

  1. Choose primary solution based on needs and resources
  2. Implement selected approach with thorough testing
  3. Update documentation to reflect new file management
  4. Configure automation for ongoing maintenance

Long-term Planning (Month 1-3)

  1. Monitor solution effectiveness and adjust as needed
  2. Optimize processes based on usage patterns
  3. Plan for growth and scaling requirements
  4. Document lessons learned for team knowledge sharing

📖 Case Study: Learn Repository Solution

Problem Statement

The Learn repository, containing conference notes and documentation, exceeded GitHub’s free Git LFS bandwidth limits, resulting in:

  • $2.73 in overage charges
  • Blocked LFS operations preventing pushes
  • Failed GitHub Actions workflows
  • Repository size approaching 1GB limit

Analysis Results

  • Git LFS usage: 0.1 GB storage, 1.0 GB bandwidth (100% of free quota)
  • Large file types: PDF presentations, video recordings, conference materials
  • Primary use case: Personal learning repository with Quarto documentation site
  • Access pattern: Frequent clones/pulls for content updates

Implemented Solution: Hybrid Approach

Phase 1: Immediate Fix (Custom Git LFS Server)

# Azure Storage account for LFS backend
RESOURCE_GROUP="learn-prod-rg-01"
STORAGE_ACCOUNT="learnprod01"

# Configure custom LFS endpoint
echo '[lfs]' > .lfsconfig
echo 'url = https://learnprod01.blob.core.windows.net/git-lfs' >> .lfsconfig

# Azure CLI authentication
git config credential."https://learnprod01.blob.core.windows.net".helper \
  "!f() { echo username=learnprod01; echo password=\$(az storage account keys list --resource-group learn-prod-rg-01 --account-name learnprod01 --query '[0].value' -o tsv); }; f"

Challenge encountered: Azure Blob Storage doesn’t natively support Git LFS API, requiring additional server implementation.

Phase 2: Alternative Solution (External Storage + GitHub Releases)

# Move large conference materials to GitHub Releases
gh release create build2025-materials \
  --title "Build 2025 Conference Materials" \
  --notes "Complete conference recordings and presentations" \
  conference-videos.zip \
  conference-presentations.zip

# Update documentation with download links
echo "[Conference Materials](https://github.com/darioairoldi/Learn/releases/tag/build2025-materials)" >> README.md

Phase 3: Repository Optimization

# Selective LFS tracking for truly large files only
git lfs untrack "*.jpg" "*.png"  # Small images back to regular Git
git lfs track "*.mp4" "*.zip"    # Keep large binaries in LFS

# Clean up .gitattributes
# Remove redundant specific file rules
# Keep pattern-based rules for maintainability

Results Achieved

  • ✅ Zero ongoing GitHub LFS costs - Moved to alternative storage
  • ✅ Unlimited storage capacity - Using Azure Blob Storage
  • ✅ Maintained Quarto functionality - Documentation site unaffected
  • ✅ Improved repository structure - Better organization of content
  • ✅ Cost-effective solution - ~$2/month for Azure storage vs ~$5+ for GitHub overages

Lessons Learned

  1. Early monitoring prevents emergencies - Set up usage alerts before hitting limits
  2. Hybrid approaches work well - Combining multiple strategies can be optimal
  3. Documentation repositories benefit from external storage - Users can access large files without Git
  4. Custom LFS servers need full API implementation - Simple storage isn’t sufficient
  5. Repository structure matters - Organization impacts both usability and costs

Ongoing Maintenance

  • Monthly review of storage usage and costs
  • Quarterly assessment of file organization
  • Annual review of solution effectiveness vs. alternatives

🎉 Conclusion

GitHub’s free tier limitations, while restrictive for large file storage and intensive CI/CD usage, can be effectively overcome through a variety of strategies. The optimal solution depends on your specific needs, technical expertise, and budget constraints.

Key Takeaways

  1. No single solution fits all scenarios - Most effective approaches combine multiple strategies
  2. Early planning prevents expensive surprises - Monitor usage and plan before hitting limits
  3. External storage is often more cost-effective - Cloud storage costs significantly less than Git LFS overages
  4. Repository organization impacts costs - Well-structured repositories naturally stay within limits
  5. Custom solutions require ongoing maintenance - Factor in operational overhead when choosing approaches

Strategic Recommendations

For Individual Developers:

  • Start with repository optimization and GitHub Releases
  • Use external storage for large documentation files
  • Monitor usage regularly to avoid surprise charges
  • Consider GitLab for projects with high LFS needs

For Small Teams:

  • Evaluate GitHub paid plans for collaboration features
  • Implement hybrid approaches (external storage + selective LFS)
  • Set up automated monitoring and optimization
  • Plan file management strategy from project start

For Organizations:

  • Invest in custom LFS infrastructure for unlimited, cost-effective storage
  • Implement comprehensive repository governance policies
  • Consider enterprise GitHub plans for advanced features and support
  • Evaluate cloud-native alternatives for CI/CD intensive workflows

Future Considerations

As cloud storage costs continue to decrease and Git LFS tooling matures, custom solutions become increasingly viable.

Organizations should regularly reassess their strategies to ensure optimal cost-effectiveness and functionality.

The landscape of repository hosting and large file management continues to evolve, with new solutions and services emerging regularly. Staying informed about these developments will help ensure your chosen strategy remains optimal over time.

📚 References

Official Documentation

  • GitHub Pricing and Plans - Official GitHub pricing information, including free tier limitations and paid plan features. Essential for understanding current limits and costs.

  • Git LFS Documentation - Comprehensive Git LFS documentation covering installation, usage, and API specifications. Required reading for understanding Git LFS internals and custom server implementation.

  • GitHub Actions Documentation - Complete guide to GitHub Actions, including usage limits, billing, and self-hosted runners. Critical for understanding CI/CD limitations and alternatives.

  • GitHub Releases Documentation - Official guidance on creating and managing GitHub releases, including file upload limitations and best practices.

Git LFS Server Implementations

  • Rudolfs - Rust Git LFS Server - High-performance Git LFS server with Azure Blob Storage support. Production-ready solution for custom LFS hosting.

  • LFS Server Go - Reference Git LFS server implementation in Go, supporting multiple storage backends including Azure and S3.

  • Git LFS S3 Server - AWS S3-based Git LFS server implementation, adaptable for Azure Blob Storage compatibility.

Alternative Git Providers

  • GitLab.com - GitLab pricing and feature comparison, including generous Git LFS allowances (10 GB storage and bandwidth free).

  • Bitbucket - Atlassian Bitbucket pricing and Git LFS support information. Alternative hosting option with competitive LFS limits.

  • Azure DevOps - Microsoft’s DevOps platform pricing, including Git repository and artifact storage options.

Cloud Storage Pricing

  • Azure Blob Storage Pricing - Detailed Azure Blob Storage pricing for different tiers (Hot, Cool, Archive), essential for calculating custom LFS server costs.

  • AWS S3 Pricing - Amazon S3 storage and data transfer pricing, useful for comparing cloud storage options for custom Git LFS implementations.

  • Google Cloud Storage Pricing - Google Cloud Platform storage pricing across different storage classes and regions.

Repository Optimization Tools

  • BFG Repo-Cleaner - Tool for removing large files from Git history safely and efficiently. Essential for repository cleanup and optimization.

  • Git Filter-Branch - Official Git documentation for history rewriting and repository cleanup. Advanced tool for repository optimization.

Technical Articles and Case Studies

Monitoring and Cost Management

  • Azure Cost Management - Tools for monitoring and optimizing Azure resource costs, essential for custom storage solutions.

  • GitHub Usage API - API endpoints for programmatically monitoring GitHub usage and billing information.

Open Source Projects and Community Resources

  • Quarto Documentation - Official Quarto documentation for static site generation, relevant for documentation repositories like the case study example.

  • Git LFS Community - Main Git LFS repository with issues, discussions, and community contributions for extending Git LFS functionality.

Document Version: 1.0
Last Updated: August 25, 2025
Authors: Dario Airoldi
Review Schedule: Quarterly (next review: November 2025)